Object Relations

Methods 

• AddRelation($object|[$objectid,$objecttype],[$relationstrength="weak"|"strong"],[REVERSE])
• Attach() - Alias to Addrelation($object|[$objectid,$objecttype],"strong");
• RemoveRelation($object|[$objectid,$objecttype])
• RemoveRelations($objecttype)
• LoadRelated($type,[REVERSE]) - Return a list of objects of $type related to the object
• FindRelated($type,[REVERSE]) - Return an array of object ids of $type related to the object (REVERSE: array of object ids of $type the object is related to)
• IsRelated($type,[REVERSE|BOTH]) - Check if relation(s) to given type of objects exist
• GetRelationList() - Return a reference to the relationlistmanager object
• On object lists:
  • LoadWithRelations(relationtype|object(list),order,[REVERSE|BOTH]]) - Load a list of objects having relations to objects of type relationtype or given object or list of objects  
  • LWPAWithRelations((array)properties,(array)attributes,array(relationtype|object(list),order,[REVERSE|BOTH]),limit,lolimit) - Load a list of objects having relations to objects of type relationtype or given object or list of objects AND properties and/or attributes as with LWPA method
• On single objects:
  • IsRelated($id, $type) - check if object is related to given object

Relation strength (type): weak / strong
 - A strong relation subjects the target object to be deleted if the (relation's) owner object id deleted, whereas in a weak relation, only the relationship is removed. Note that if the target object is deleted, the relation's owner remains unaffected regardless of the strength of the relation, making the relation directional in a sense.

REVERSE ( define("REVERSE","REVERSE"); ): Add a reverse relation; substitutes owner / target fields and thus reverses the direction of the relation.

SAMPLES

$User->Attach($image)      (  User ->> Image )    $image->AddRelation($User,'strong',REVERSE)
same as: $image->AttachTo($User) 

$User->AddRelation($image)  (  User -> Image  )  $image->AddRelation($User,'weak',REVERSE)

$User->AddRelation($image,'strong',REVERSE)  ( User

$User->AddRelation($image,'weak','REVERSE)   (  UserAddRelation($User);

 

$User->LoadRelated('image')         Loads items with relation   User -> Image,   User->> Image

$User->LoadRelated('image',REVERSE)   Loads items with relation User

 

Order of results

You can optionally sort the order of the result list by giving the sorting field(s) as the last parameter, with the direction (ASC / DESC).
Notice: Direction is needed for the method to recognize parameter as sort order.

Example:  $resultlist = $object->LoadRelated($type,"name ASC");

Example 1: Attach an image to a news object 

$imageid=2;
$newsmanager=new NewsManager($dbc,$log,$newsid);
$newsmanager->AddRelation($imageid,"image");

Example 2: Save a comment and attach it to a blogentry 
(Delete comment if blogentry is deleted)

irequire("forms");
$postdata=new Forms();
$data=$postdata->GetObject("comment_");

$comment=new CommentManager($dbc,$log);
$comment->SafeInsert($data);
$comment->Save();

$blogentry=new BlogentryManager($dbc,$log,$blogentryid);
$blogentry->AddRelation($comment,"strong");
//Could be also written as:

//$blogentry->Attach($comment); 

Example 3, live demo of adding and removing relations @ :http://dev1.innoventum.fi/innoventum/tools/relationtest

Source:

irequire("bulletinpostmanager","icms_core");
/* Use a bulletinpost as the object to have some goodness */
$post=new BulletinPostManager($dbc,$log,1);

/* We may have linked some images to the bulletinpost, let's try to load them */
echo("Load related images");

/* Get a list of imagemanager objects maybe */
$images=$post->LoadRelated("image");

/* Get a list of ids for attached objects of type "image" maybe */
$imageids=$post->FindRelated("image");
if(is_array($imageids))
    {
    echo("Imploded array of related images (FindRelated): ".implode(",",$imageids)." 
");
    }
else echo("Array of related images turned out as ".gettype($imageids)." instead.
");
if(is_object($images))
    {

    if(!$images->IsEmpty())
        {
            /* Okay, there were linked images and we've got a list of them. Let's play. */
        do {
            
            /* List images */
            echo("Related image: ".$images->GetProperty("id")." imageurl: ".$images->GetImageUrl(500)."
");
            
            /* Remove the relation using the image object */
            echo("Now remove relation :".(($post->RemoveRelation($images->GetObject())===true)?'OK':'Failed')."
");
            // $post->RemoveRelation($images->GetProperty("id"),"image"); works just as well..
            
            }while($images->Next());
        }    
        
    }
else {
    echo("Fail, gots ".gettype($images)." instead of an object
");
    echo("Let's add a relation then.");
    /* Add a relation to an image. (defaults to a weak relation.) */
    $addids=array(2,30,53);
    foreach($addids as $id)
        {
        echo("AddRelation(".$id.",\"image\"):");
        if($post->AddRelation($id,"image"))
            echo(" .. done
");
        else echo ("failed.
");
        }
    }